home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 October: Mac OS SDK / Dev.CD Oct 97 SDK1.toast / Development Kits (Disc 1) / Interfaces&Libraries / Universal / Interfaces / CIncludes / Unicode.h < prev    next >
Encoding:
C/C++ Source or Header  |  1997-08-12  |  12.9 KB  |  390 lines  |  [TEXT/MPS ]
  1. /*
  2.      File:        Unicode.h
  3.  
  4.      Contains:    Types, constants, and prototypes for Unicode Converter
  5.  
  6.      Version:    Technology:    Mac OS 8 (Tempo)
  7.                  Release:    Universal Interfaces 3.0.1
  8.  
  9.      Copyright:    © 1994-1997 by Apple Computer, Inc., all rights reserved.
  10.  
  11.      Bugs?:        Please include the the file and version information (from above) with
  12.                  the problem description.  Developers belonging to one of the Apple
  13.                  developer programs can submit bug reports to:
  14.  
  15.                      devsupport@apple.com
  16.  
  17. */
  18. #ifndef __UNICODE__
  19. #define __UNICODE__
  20.  
  21. #ifndef __TYPES__
  22. #include <Types.h>
  23. #endif
  24. #ifndef __TEXTCOMMON__
  25. #include <TextCommon.h>
  26. #endif
  27. #ifndef __MIXEDMODE__
  28. #include <MixedMode.h>
  29. #endif
  30.  
  31.  
  32.  
  33. #if PRAGMA_ONCE
  34. #pragma once
  35. #endif
  36.  
  37. #ifdef __cplusplus
  38. extern "C" {
  39. #endif
  40.  
  41. #if PRAGMA_IMPORT
  42. #pragma import on
  43. #endif
  44.  
  45. #if PRAGMA_STRUCT_ALIGN
  46.     #pragma options align=mac68k
  47. #elif PRAGMA_STRUCT_PACKPUSH
  48.     #pragma pack(push, 2)
  49. #elif PRAGMA_STRUCT_PACK
  50.     #pragma pack(2)
  51. #endif
  52.  
  53. /* Unicode conversion contexts: */
  54. typedef struct OpaqueTextToUnicodeInfo*  TextToUnicodeInfo;
  55. typedef struct OpaqueUnicodeToTextInfo*  UnicodeToTextInfo;
  56. typedef struct OpaqueUnicodeToTextRunInfo*  UnicodeToTextRunInfo;
  57. typedef const TextToUnicodeInfo         ConstTextToUnicodeInfo;
  58. typedef const UnicodeToTextInfo         ConstUnicodeToTextInfo;
  59. /* UnicodeMapVersion type & values */
  60. typedef SInt32                             UnicodeMapVersion;
  61.  
  62. enum {
  63.     kUnicodeUseLatestMapping    = -1
  64. };
  65.  
  66. /* Types used in conversion */
  67. struct UnicodeMapping {
  68.     TextEncoding                     unicodeEncoding;
  69.     TextEncoding                     otherEncoding;
  70.     UnicodeMapVersion                 mappingVersion;
  71. };
  72. typedef struct UnicodeMapping UnicodeMapping;
  73.  
  74. typedef UnicodeMapping *                UnicodeMappingPtr;
  75. typedef const UnicodeMapping *            ConstUnicodeMappingPtr;
  76. /* Control flags for ConvertFromUnicodeToText and ConvertFromTextToUnicode */
  77.  
  78. enum {
  79.     kUnicodeUseFallbacksBit        = 0,
  80.     kUnicodeKeepInfoBit            = 1,
  81.     kUnicodeDirectionalityBits    = 2,
  82.     kUnicodeVerticalFormBit        = 4,
  83.     kUnicodeLooseMappingsBit    = 5,
  84.     kUnicodeStringUnterminatedBit = 6,
  85.     kUnicodeTextRunBit            = 7,
  86.     kUnicodeKeepSameEncodingBit    = 8
  87. };
  88.  
  89.  
  90. enum {
  91.     kUnicodeUseFallbacksMask    = 1L << kUnicodeUseFallbacksBit,
  92.     kUnicodeKeepInfoMask        = 1L << kUnicodeKeepInfoBit,
  93.     kUnicodeDirectionalityMask    = 3L << kUnicodeDirectionalityBits,
  94.     kUnicodeVerticalFormMask    = 1L << kUnicodeVerticalFormBit,
  95.     kUnicodeLooseMappingsMask    = 1L << kUnicodeLooseMappingsBit,
  96.     kUnicodeStringUnterminatedMask = 1L << kUnicodeStringUnterminatedBit,
  97.     kUnicodeTextRunMask            = 1L << kUnicodeTextRunBit,
  98.     kUnicodeKeepSameEncodingMask = 1L << kUnicodeKeepSameEncodingBit
  99. };
  100.  
  101. /* Values for kUnicodeDirectionality field */
  102.  
  103. enum {
  104.     kUnicodeDefaultDirection    = 0,
  105.     kUnicodeLeftToRight            = 1,
  106.     kUnicodeRightToLeft            = 2
  107. };
  108.  
  109. /* Directionality masks for control flags */
  110.  
  111. enum {
  112.     kUnicodeDefaultDirectionMask = kUnicodeDefaultDirection << kUnicodeDirectionalityBits,
  113.     kUnicodeLeftToRightMask        = kUnicodeLeftToRight << kUnicodeDirectionalityBits,
  114.     kUnicodeRightToLeftMask        = kUnicodeRightToLeft << kUnicodeDirectionalityBits
  115. };
  116.  
  117. /* Control flags for TruncateForUnicodeToText: */
  118. /*
  119.    Now TruncateForUnicodeToText uses control flags from the same set as used by
  120.    ConvertFromTextToUnicode, ConvertFromUnicodeToText, etc., but only
  121.    kUnicodeStringUnterminatedMask is meaningful for TruncateForUnicodeToText.
  122.    
  123.    Previously two special control flags were defined for TruncateForUnicodeToText:
  124.           kUnicodeTextElementSafeBit = 0
  125.           kUnicodeRestartSafeBit = 1
  126.    However, neither of these was implemented.
  127.    Instead of implementing kUnicodeTextElementSafeBit, we now use
  128.    kUnicodeStringUnterminatedMask since it accomplishes the same thing and avoids
  129.    having special flags just for TruncateForUnicodeToText
  130.    Also, kUnicodeRestartSafeBit is unnecessary, since restart-safeness is handled by
  131.    setting kUnicodeKeepInfoBit with ConvertFromUnicodeToText.
  132.    If TruncateForUnicodeToText is called with one or both of the old special control
  133.    flags set (bits 0 or 1), it will not generate a paramErr, but the old bits have no
  134.    effect on its operation.
  135. */
  136.  
  137. /* Filter bits for filter field in QueryUnicodeMappings and CountUnicodeMappings: */
  138.  
  139. enum {
  140.     kUnicodeMatchUnicodeBaseBit    = 0,
  141.     kUnicodeMatchUnicodeVariantBit = 1,
  142.     kUnicodeMatchUnicodeFormatBit = 2,
  143.     kUnicodeMatchOtherBaseBit    = 3,
  144.     kUnicodeMatchOtherVariantBit = 4,
  145.     kUnicodeMatchOtherFormatBit    = 5
  146. };
  147.  
  148.  
  149. enum {
  150.     kUnicodeMatchUnicodeBaseMask = 1L << kUnicodeMatchUnicodeBaseBit,
  151.     kUnicodeMatchUnicodeVariantMask = 1L << kUnicodeMatchUnicodeVariantBit,
  152.     kUnicodeMatchUnicodeFormatMask = 1L << kUnicodeMatchUnicodeFormatBit,
  153.     kUnicodeMatchOtherBaseMask    = 1L << kUnicodeMatchOtherBaseBit,
  154.     kUnicodeMatchOtherVariantMask = 1L << kUnicodeMatchOtherVariantBit,
  155.     kUnicodeMatchOtherFormatMask = 1L << kUnicodeMatchOtherFormatBit
  156. };
  157.  
  158. /* Control flags for SetFallbackUnicodeToText */
  159.  
  160. enum {
  161.     kUnicodeFallbackSequencingBits = 0
  162. };
  163.  
  164.  
  165. enum {
  166.     kUnicodeFallbackSequencingMask = 3L << kUnicodeFallbackSequencingBits
  167. };
  168.  
  169. /* values for kUnicodeFallbackSequencing field */
  170.  
  171. enum {
  172.     kUnicodeFallbackDefaultOnly    = 0L,
  173.     kUnicodeFallbackCustomOnly    = 1L,
  174.     kUnicodeFallbackDefaultFirst = 2L,
  175.     kUnicodeFallbackCustomFirst    = 3L
  176. };
  177.  
  178.  
  179. /* Caller-supplied entry point to a fallback handler */
  180. typedef CALLBACK_API( OSStatus , UnicodeToTextFallbackProcPtr )(UniChar *iSrcUniStr, ByteCount iSrcUniStrLen, ByteCount *oSrcConvLen, TextPtr oDestStr, ByteCount iDestStrLen, ByteCount *oDestConvLen, LogicalAddress iInfoPtr, ConstUnicodeMappingPtr iUnicodeMappingPtr);
  181. typedef STACK_UPP_TYPE(UnicodeToTextFallbackProcPtr)             UnicodeToTextFallbackUPP;
  182. enum { uppUnicodeToTextFallbackProcInfo = 0x003FFFF0 };         /* pascal 4_bytes Func(4_bytes, 4_bytes, 4_bytes, 4_bytes, 4_bytes, 4_bytes, 4_bytes, 4_bytes) */
  183. #define NewUnicodeToTextFallbackProc(userRoutine)                 (UnicodeToTextFallbackUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppUnicodeToTextFallbackProcInfo, GetCurrentArchitecture())
  184. #define CallUnicodeToTextFallbackProc(userRoutine, iSrcUniStr, iSrcUniStrLen, oSrcConvLen, oDestStr, iDestStrLen, oDestConvLen, iInfoPtr, iUnicodeMappingPtr)  CALL_EIGHT_PARAMETER_UPP((userRoutine), uppUnicodeToTextFallbackProcInfo, (iSrcUniStr), (iSrcUniStrLen), (oSrcConvLen), (oDestStr), (iDestStrLen), (oDestConvLen), (iInfoPtr), (iUnicodeMappingPtr))
  185. /* Function prototypes */
  186. #if GENERATING68K
  187. /* Rounite to Initialize the Unicode Converter and cleanup once done with it */
  188. EXTERN_API( OSStatus )
  189. InitializeUnicode                (StringPtr                 TECFileName);
  190.  
  191. EXTERN_API( void )
  192. TerminateUnicode                (void);
  193.  
  194. #endif  /* GENERATING68K */
  195.  
  196. EXTERN_API( OSStatus )
  197. CreateTextToUnicodeInfo            (ConstUnicodeMappingPtr  iUnicodeMapping,
  198.                                  TextToUnicodeInfo *    oTextToUnicodeInfo);
  199.  
  200. EXTERN_API( OSStatus )
  201. CreateTextToUnicodeInfoByEncoding (TextEncoding         iEncoding,
  202.                                  TextToUnicodeInfo *    oTextToUnicodeInfo);
  203.  
  204. EXTERN_API( OSStatus )
  205. CreateUnicodeToTextInfo            (ConstUnicodeMappingPtr  iUnicodeMapping,
  206.                                  UnicodeToTextInfo *    oUnicodeToTextInfo);
  207.  
  208. EXTERN_API( OSStatus )
  209. CreateUnicodeToTextInfoByEncoding (TextEncoding         iEncoding,
  210.                                  UnicodeToTextInfo *    oUnicodeToTextInfo);
  211.  
  212. EXTERN_API( OSStatus )
  213. CreateUnicodeToTextRunInfo        (ItemCount                 iNumberOfMappings,
  214.                                  const UnicodeMapping     iUnicodeMappings[],
  215.                                  UnicodeToTextRunInfo *    oUnicodeToTextInfo);
  216.  
  217. EXTERN_API( OSStatus )
  218. CreateUnicodeToTextRunInfoByEncoding (ItemCount         iNumberOfEncodings,
  219.                                  const TextEncoding     iEncodings[],
  220.                                  UnicodeToTextRunInfo *    oUnicodeToTextInfo);
  221.  
  222. EXTERN_API( OSStatus )
  223. CreateUnicodeToTextRunInfoByScriptCode (ItemCount         iNumberOfScriptCodes,
  224.                                  const ScriptCode         iScripts[],
  225.                                  UnicodeToTextRunInfo *    oUnicodeToTextInfo);
  226.  
  227. /* Change the TextToUnicodeInfo to another mapping. */
  228. EXTERN_API( OSStatus )
  229. ChangeTextToUnicodeInfo            (TextToUnicodeInfo         ioTextToUnicodeInfo,
  230.                                  ConstUnicodeMappingPtr  iUnicodeMapping);
  231.  
  232. /* Change the UnicodeToTextInfo to another mapping. */
  233. EXTERN_API( OSStatus )
  234. ChangeUnicodeToTextInfo            (UnicodeToTextInfo         ioUnicodeToTextInfo,
  235.                                  ConstUnicodeMappingPtr  iUnicodeMapping);
  236.  
  237. EXTERN_API( OSStatus )
  238. DisposeTextToUnicodeInfo        (TextToUnicodeInfo *    ioTextToUnicodeInfo);
  239.  
  240. EXTERN_API( OSStatus )
  241. DisposeUnicodeToTextInfo        (UnicodeToTextInfo *    ioUnicodeToTextInfo);
  242.  
  243. EXTERN_API( OSStatus )
  244. DisposeUnicodeToTextRunInfo        (UnicodeToTextRunInfo *    ioUnicodeToTextRunInfo);
  245.  
  246. EXTERN_API( OSStatus )
  247. ConvertFromTextToUnicode        (TextToUnicodeInfo         iTextToUnicodeInfo,
  248.                                  ByteCount                 iSourceLen,
  249.                                  ConstLogicalAddress     iSourceStr,
  250.                                  OptionBits             iControlFlags,
  251.                                  ItemCount                 iOffsetCount,
  252.                                  ByteOffset             iOffsetArray[],
  253.                                  ItemCount *            oOffsetCount,
  254.                                  ByteOffset             oOffsetArray[],
  255.                                  ByteCount                 iOutputBufLen,
  256.                                  ByteCount *            oSourceRead,
  257.                                  ByteCount *            oUnicodeLen,
  258.                                  UniCharArrayPtr         oUnicodeStr);
  259.  
  260. EXTERN_API( OSStatus )
  261. ConvertFromUnicodeToText        (UnicodeToTextInfo         iUnicodeToTextInfo,
  262.                                  ByteCount                 iUnicodeLen,
  263.                                  ConstUniCharArrayPtr     iUnicodeStr,
  264.                                  OptionBits             iControlFlags,
  265.                                  ItemCount                 iOffsetCount,
  266.                                  ByteOffset             iOffsetArray[],
  267.                                  ItemCount *            oOffsetCount,
  268.                                  ByteOffset             oOffsetArray[],
  269.                                  ByteCount                 iOutputBufLen,
  270.                                  ByteCount *            oInputRead,
  271.                                  ByteCount *            oOutputLen,
  272.                                  LogicalAddress         oOutputStr);
  273.  
  274. EXTERN_API( OSStatus )
  275. ConvertFromUnicodeToTextRun        (UnicodeToTextRunInfo     iUnicodeToTextInfo,
  276.                                  ByteCount                 iUnicodeLen,
  277.                                  ConstUniCharArrayPtr     iUnicodeStr,
  278.                                  OptionBits             iControlFlags,
  279.                                  ItemCount                 iOffsetCount,
  280.                                  ByteOffset             iOffsetArray[],
  281.                                  ItemCount *            oOffsetCount,
  282.                                  ByteOffset             oOffsetArray[],
  283.                                  ByteCount                 iOutputBufLen,
  284.                                  ByteCount *            oInputRead,
  285.                                  ByteCount *            oOutputLen,
  286.                                  LogicalAddress         oOutputStr,
  287.                                  ItemCount                 iEncodingRunBufLen,
  288.                                  ItemCount *            oEncodingRunOutLen,
  289.                                  TextEncodingRun         oEncodingRuns[]);
  290.  
  291. EXTERN_API( OSStatus )
  292. ConvertFromUnicodeToScriptCodeRun (UnicodeToTextRunInfo  iUnicodeToTextInfo,
  293.                                  ByteCount                 iUnicodeLen,
  294.                                  ConstUniCharArrayPtr     iUnicodeStr,
  295.                                  OptionBits             iControlFlags,
  296.                                  ItemCount                 iOffsetCount,
  297.                                  ByteOffset             iOffsetArray[],
  298.                                  ItemCount *            oOffsetCount,
  299.                                  ByteOffset             oOffsetArray[],
  300.                                  ByteCount                 iOutputBufLen,
  301.                                  ByteCount *            oInputRead,
  302.                                  ByteCount *            oOutputLen,
  303.                                  LogicalAddress         oOutputStr,
  304.                                  ItemCount                 iScriptRunBufLen,
  305.                                  ItemCount *            oScriptRunOutLen,
  306.                                  ScriptCodeRun             oScriptCodeRuns[]);
  307.  
  308. /* Truncate a multibyte string at a safe place. */
  309. EXTERN_API( OSStatus )
  310. TruncateForTextToUnicode        (ConstTextToUnicodeInfo  iTextToUnicodeInfo,
  311.                                  ByteCount                 iSourceLen,
  312.                                  ConstLogicalAddress     iSourceStr,
  313.                                  ByteCount                 iMaxLen,
  314.                                  ByteCount *            oTruncatedLen);
  315.  
  316. /* Truncate a Unicode string at a safe place. */
  317. EXTERN_API( OSStatus )
  318. TruncateForUnicodeToText        (ConstUnicodeToTextInfo  iUnicodeToTextInfo,
  319.                                  ByteCount                 iSourceLen,
  320.                                  ConstUniCharArrayPtr     iSourceStr,
  321.                                  OptionBits             iControlFlags,
  322.                                  ByteCount                 iMaxLen,
  323.                                  ByteCount *            oTruncatedLen);
  324.  
  325. /* Convert a Pascal string to Unicode string. */
  326. EXTERN_API( OSStatus )
  327. ConvertFromPStringToUnicode        (TextToUnicodeInfo         iTextToUnicodeInfo,
  328.                                  ConstStr255Param         iPascalStr,
  329.                                  ByteCount                 iOutputBufLen,
  330.                                  ByteCount *            oUnicodeLen,
  331.                                  UniCharArrayPtr         oUnicodeStr);
  332.  
  333. /* Convert a Unicode string to Pascal string. */
  334. EXTERN_API( OSStatus )
  335. ConvertFromUnicodeToPString        (UnicodeToTextInfo         iUnicodeToTextInfo,
  336.                                  ByteCount                 iUnicodeLen,
  337.                                  ConstUniCharArrayPtr     iUnicodeStr,
  338.                                  Str255                 oPascalStr);
  339.  
  340. /* Count the available conversion mappings. */
  341. EXTERN_API( OSStatus )
  342. CountUnicodeMappings            (OptionBits             iFilter,
  343.                                  ConstUnicodeMappingPtr  iFindMapping,
  344.                                  ItemCount *            oActualCount);
  345.  
  346. /* Get a list of the available conversion mappings. */
  347. EXTERN_API( OSStatus )
  348. QueryUnicodeMappings            (OptionBits             iFilter,
  349.                                  ConstUnicodeMappingPtr  iFindMapping,
  350.                                  ItemCount                 iMaxCount,
  351.                                  ItemCount *            oActualCount,
  352.                                  UnicodeMapping         oReturnedMappings[]);
  353.  
  354. /* Setup the fallback handler for converting Unicode To Text. */
  355. EXTERN_API( OSStatus )
  356. SetFallbackUnicodeToText        (UnicodeToTextInfo         iUnicodeToTextInfo,
  357.                                  UnicodeToTextFallbackUPP  iFallback,
  358.                                  OptionBits             iControlFlags,
  359.                                  LogicalAddress         iInfoPtr);
  360.  
  361. /* Setup the fallback handler for converting Unicode To TextRuns. */
  362. EXTERN_API( OSStatus )
  363. SetFallbackUnicodeToTextRun        (UnicodeToTextRunInfo     iUnicodeToTextRunInfo,
  364.                                  UnicodeToTextFallbackUPP  iFallback,
  365.                                  OptionBits             iControlFlags,
  366.                                  LogicalAddress         iInfoPtr);
  367.  
  368.  
  369.  
  370. #if PRAGMA_STRUCT_ALIGN
  371.     #pragma options align=reset
  372. #elif PRAGMA_STRUCT_PACKPUSH
  373.     #pragma pack(pop)
  374. #elif PRAGMA_STRUCT_PACK
  375.     #pragma pack()
  376. #endif
  377.  
  378. #ifdef PRAGMA_IMPORT_OFF
  379. #pragma import off
  380. #elif PRAGMA_IMPORT
  381. #pragma import reset
  382. #endif
  383.  
  384. #ifdef __cplusplus
  385. }
  386. #endif
  387.  
  388. #endif /* __UNICODE__ */
  389.  
  390.